TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/(A)TB/(A)TBE.ADF/Utility/README_LS

Text File | 1989-09-12 | 16KB | 384 lines

README                ls v4.0k                05/11/90

ls v4.0k is (c) Copyright 1990, Kim E. DeVaughn, all rights reserved.


Introduction:

What?!  Another version of "ls" ...?  Why in the world does the world
need Yet Another Version of such a common command?  Actually, that's
the answer (as well as the question).

If you kept track of such things (like some operating systems do),
you'd probably find the "most executed" command is by far, "ls" (or
dir, etc).

We use "ls" not only to see what's where, but when what's there got
there, how big it is, what it's attributes are, etc. We also use "ls"
to check our spelling, make lists of files, and so forth.

Because of this high usage, we'd like it to work the way we think it
ought to, or at least the way we're used to. For alot of people, this
means "like UNIX(R)".*  Not that the UNIX way is the *best* way, but
when you have to deal with UNIX at work, etc, it makes it much more
convenient and productive (not to mention much less error prone), to
have the Amiga environment "similar".  At least in the CLI/shell
environment.

     * - UNIX is a registered trademark of AT&T, if you didn't know.
To that end, I've reworked Justin McCormick's "ls" (v3.1) so it's
output and option flags (where applicable) are much closer to UNIX's
implementation, by default. It still isn't a "perfect" emulation, but
it's quite close.

Along the way, I've fixed a number of bugs (none terribly major),
added some additional features, and just about run out of letters for
the option flags!

If Justin thought "ls" was getting bloated with options in his most
recent rev (v3.1), he'll surely gag after seeing what I've done :-).
 Still, with all the new options, etc, "ls" is only about 16K. And it
can still be made resident, etc. In fact, with the right set of
switches, you can make it behave just like v3.1 (bug fixes excepted)
if you want!

The reason for this is that I'm a very firm believer in letting
people "have it their way". I'm sure I could chop out about 4K or
more if I just did it "my way", but other people have other ideas.
 The default way however, *is* "my way".. or actually "the UNIX way".

  [ BTW ... if you want this version of "ls" to look/work like v3.1,
the [following switches will do it for you:  -AMSWbemoqv ... :-)]

Installation:

Just copy "ls" to a directory in your path. If the "p" (pure) bit has
been stripped of somewhere along the way, you can turn it on using
the Protect command (or chmod, etc) if you want to make "ls" a
"resident" command.


Distribution:

Here is a listing of what you should have received in this
distribution:

-----rw-d   7     2444  May 10 18:23  License
-----rw-d      33    15901  Jun  5 11:31  README
-----rw-d   4     1204  Jun  5 11:09  README.1ST
---p-rwxd      34    16028  May 11 02:13  ls
-----rw-d      43    20124  May 11 09:46  ls.doc
d----rwxd   1    0  Jun  5 10:35  src
Dirs: 1    Files: 5 Blocks: 122   Bytes: 54949

src:
-----rw-d   2      457  May 10 19:07  Linkfile
-----rw-d   3      590  May 10 18:52  Makefile
-----rw-d     137    65576  May 11 02:02  ls.c
-----rw-d   9     3685  May 10 18:53  ls.h
-----rw-d      73    34948  May 10 18:51  lssup.a
-----rw-d      12     5160  Jul 29  1989  mycres.a
-----rw-d   4     1104  Jul 29  1989  mycres.o
Dirs: 0    Files: 7 Blocks: 240   Bytes: 111520

Totals:
Dirs: 1    Files: 12    Blocks: 362   Bytes: 166469


What's New  (see "ls.doc" for details, etc):

    o  New (default) long listing format that *looks* like UNIX's
(except for things like owner, group ID, etc).

    o  Block sizes now include *all* blocks associated with a file,
and are finally accurate for FFS devices.

    o  By default, upper/lower case *is* significant in the output
listing, and in the wildcard pattern matching.

    o  By default, directories and files are intermixed, according to
their alphabetic position.

    o  By default, the short listing format uses fixed width columns,
based on the length of the longest filename in the directory.
Variable width columns are still available.

    o  By default, "hidden", "*.info", and "dot" files (eg, .foo) are
not displayed. There are switches for each, as well as an "all" flag.

    o  Several new options like the ability to limit the "-R"
recursion depth; ability to show absolute and relative path names in
the long format listing; additional control of directory header and
totalization lines; elimination of redundent totalization lines;
showing/sorting on files' "disk keys"; control of the date format;
sort by date/size defaults to newest/biggest first; and a few other
things.

    o  Improved error handling and error msgs.  Better "break"
handling. No more "memory leaks" (yes, there is one in v3.1 ... it
looses 300 bytes on an error exit).

    o  The assignment of option flags has been "rationalized".
 Applicable flags from the UNIX "ls" were assigned 1st, followed by
other flags from v3.1, followed by new flags added in this rev.
However ... some flag assignments from previous revs were changed
when better mnemonic values could be found, etc. So ... check the
usage, and/or docs. Caveat emptor!

    o  Flags requiring arguments (eg, -N) may or may not be seperated
from the argument by spaces. So, "-Nfoo" is just as legal as "-N
foo".



What's Not (yet) Done ... and Limitations/Caveats:

    o  Wildcard expansion is still done by "ls", rather than left to
the shell to do so (which is where it should be done, IMHO). This is
to avoid the braindead limitation of being able to pass a command
line of only 255 chars or so max to Exec() under AmigaOS 1.3.
 Hopefully this limit will be removed under AmigaOS 2.0.

       This also means that if the shell you're using expands normal
wildcards ("*" and "?") itself, you need to "quote" the wildcards in
some manner for "ls" to work as intended. Depending on the shell you
use, things like "*" or \* or '* may work. See your shell
documentation.

    o  Each "fully named path" is still processed seperately, and
will give you an automatic "long format list" for each file
 encountered, or a "short format list" for each subdirectory
encountered. This is why you will get some rather weird output
listings if you let your shell expand wildcards, rather than passing
the wildcards intact to "ls".   (A "fully named path" is a filespec
that contains no wildcards ... in other words, an actual file or dir
name).

       This will change. How it wiil change is somewhat dependent on
what is done in AmigaOS 2.0 with command line length limits, links,
etc.

    o  Many flag settings get reset to the default values between
each "fully named path". Some do not, and are identified in "ls.doc"
as being "sticky".

       This will change when the "fully named path" and wildcard
expansion issues are resolved.

    o  Doesn't support AmigaOS v2.0 links (or any other 2.0
enhancements), since CBM hasn't finalized it (besides, I don't have
2.0 yet).

    o  I want to allow the user to override the default operation
with flags provided in environment variables. This will require
reworking "ls's" startup code (or the use of the standard "cres",
with accompanying bloat of the executable) due to the current env var
implementation as files.  Dumb.

    o  The filename arguments required for the -N and -O options must
be fully specified.  Wildcards don't work here.

    o  The -N and -O options accept only filenames; they do not
accept actual dates.

    o  You must hit "return" to clear the short format's builtin
pager's "More ..." line (see -I), and continue with the listing. I'd
like to change this to being able to hit any key.

       Also, the builtin pager works only on a directory-by-directory
basis. It'd be nice (read: this probably won't happen) if it worked
on the output as a whole. And if it worked with the long format
listing.

    o  When a long format listing is requested of a "psuedo-device",
the block count may be inaccurate, since such "devices" do not
necessarily have an inherent (or constant) bytes/block value.
Currently, the only such case known are assignments made with the
"pathass" utility. When this situation occurs, a warning message is
issued to the effect that the block counts may be inaccurate.


Known Bugs:

    o  Multiple wildcards in a given path do not work properly. For
example, the command: "ls ls*/*.o" lists the entire contents of the
"ls40" subdirectory, not just the ".o" files.

    o  Certain options are slightly incompatible. The known instances
occur with the old (v3.1) long format, and the variable column form
of the short format, as I didn't touch that code much. Known
instances are:

       Show keys (-K) does not work with the old (-o) long format.

       Append "/" to dir names (-p) does not work with the variable
       column short format (-vp will NOT append a "/"). However, if
       no ANSI escape sequences (-E) is specified along with -v, they
       will be appended to dir names. This is the same behavior as
       "ls" v3.1.

    o  Seperate subdir totalization for "fully named path" entries
does not work. However, their contribution to a grand total (-T) is
included.



Quick Look:

usage: ls [ [-options <args>]  [names] ] ...
  a  Show dot files   s  Sort by size       M  Ignore case w/wildcard
  b  Show data blks   t  Sort by date       N <name> Show newer than
  c  Show filenotes   u  Usage  [also -?]   O <name> Show older than
  d  Show dirs only   v  Vari col short list  P Show full pathnames
  e  Execute bit is "e"  x <pat> Exclude files  Q Requesters enabled
  f  Show files only     z  Override blk calc   R Recursive listing
  h  Show hidden files   A  Show all  [= -ahi]  S  Show dirs first
  i  Show *.info files   B <blk> Force blk size T  Totals for all
                                                   entries
  k  Sort by disk key    C  Single column list  V  Show rel pathnames
  l  Long listing     D Show dirs last     W  No contents (wild dir)
  m  Mixed case output  E  No ANSI escape codes  X <wide> Set output
                                                    cols
  n  No sort          G  No subdir totals        Y <high> Set output
                                                    rows
  o  Old long list fmt  H No headings        Z  Force ANSI sequences
  p  Append "/" to dirs   I  No page prompts   0-6 Date format (new
                                                   long)
  q  Quit on not found   K  Show disk keys     -  Next arg is
                                                  filename
  r  Reverse sort     L <n> Limited recursion
  F <format> Format output [-o fmt] (default: "%p %d %t %4b %8s
 %n\n")



Tech Notes:

    o  This version of "ls" was compiled/assembled using Lattice
v5.05, with optimization on. See the Makefile and Linkfile for
details. Also note that to use the source level debugger "cpr", you
need to use one of the commented out CFLAG strings in the Makefile
with -d3, as well as uncommenting the ADDSYM statement in the
Linkfile.

    o  The file "mycres.o" is included, as I couldn't get "mycres.a"
to assemble ... no includes called "exec/funcdef.i" anywhere I could
find, etc. I didn't have a real reason to muck with that code, so I
didn't pursue the matter. The "mycres.o" file is from the v3.1
distribution, and works fine (except when you try using getenv() .).

    o  My enhancements to "ls" have evolved bit-by-bit over a period
of about a year. Consequently, the code is somewhat less than
"pristine". I'm sure it can be cleaned up a bit, though I tried to
keep my changes from getting too ugly. Also, I've tried to more or
less stay with Justin's coding style, but I know that hasn't been
completely successful either.
       Anyway, you've been warned; if you go reading the code, send
flames to /dev/null ... :-)



Revision History:

    Kim E. DeVaughn

    v4.0k  May 11, 1990  Pretty much completely revised the output
formats. Much more like UNIX's "ls" in its output, options, etc.
Several bugs fixed.  Many new options.

    Justin V. McCormick

    v3.1  July 29, 1989  Bug fixes, new output width and height
options.
    v3.0  July 25, 1989  Instant sorting, best-fit output, new
features.
    v2.2  December 1988  Fixed status return and multiple wildcard
pathnames.
    v2.1  December 1988  Minor size reduction, fixed a few bugs from
 2.0.
    v2.0  November 1988  Revised for Lattice 5.0 and made 1.3 compatible.
    v1.0    August 1986  Written from scratch, my first Amiga project.



Acknowledgements, Etc:

First, let me thank Justin McCormick for providing "ls" v3.1, and the
very good algorithms from which I was able to build upon. His inline
sorting in particular made his version the one I chose to enhance
because of it's speed.

A very excellent job, and my sincere thanks go to him for a job well
done!

Second, let me thank Tom Rokicki for the "date" algorithm I used, and
to Rob Peck for publishing it in his excellent book, "Programmer's
Guide to the Amiga" (Sybex).  Both of these people have contributed
much to the Amiga development community!

Third, I want to thank Matt Dillon for providing his fine DME editor,
and many, *many* examples of how to program the Amiga. If you ever
need to know how to do something, take a look a Matt's code ...
chances are he's done it, and in a lean, mean, fast way!


Finally, I want to mention that this version of "ls" is copyrighted,
whereas Justin's previous versions were explicitly "public domain".
Specifically, I am copyrighting this version of the executable "ls",
the "ls.c" and "ls.h" source files, and the "ls.doc" and "README"
files.

This is completely legal, since the base version I used had been
declared to be in the "public domain". I feel totally justified in
doing so due to the extensive changes that I've made.

You'll note, if you read the "License", that I'm not trying to
restrict the use or redistribution of this version of "ls", other
than to insure that it isn't used by anyone to make money out of,
myself included. In particular, certain "diskzines" seem to be
unscrupulously "raiding" the freely redistrib-utable software base
lately, in an attempt to help sell their disk/magazines.

Most of the ones I've seen are *trash*, and the prices they charge
are a bit outrageous, considering what they provide. I do not wish to
help them.  Not even in a slight way.

Anyway, I hope nobody has a big problem with this. If you do, lemee
hear from you.



The Future:

There will definitely be at least one more release of my version of
"ls". It will address those items mentioned in the "What's Not Done"
and "Known Bugs" sections above. In particular, it will support
AmigaOS 2.0's enhancements, such as links. Given 2.0's probable
availability, I doubt this will happen much before the end of 1990.
We shall see.

In the meantime, let me hear from you if there are things you like
(or don't). And especially if you find any bugs, "features", or
anomalies. And if (God forbid), there's a useful option I've managed
to overlook, don't hesitate to put in a request ... there are still a
few option flags left ... :-)

In addition to my electronic addresses (see signature below), I can
be reached at:

    Kim E. DeVaughn
    750 Sylvan Av,  #32
    Mt. View, CA  94041

However, email to my USENET/UUCP address is probably the surest way
to get in touch with me, and should be used if at all possible.

/kim   /\oo/\

--
UUCP:  [e-mail]
  or:  {sun,decwrl,hplabs,pyramid,uunet,oliveb,ames}!amdahl!kim
DDD:   408-746-8462
USPS:  Amdahl Corp.  M/S 249,  1250 E. Arques Av,  Sunnyvale, CA 94086
BIX:   kdevaughn     GEnie:   K.DEVAUGHN     CIS:   76535,25